/*
 * This file is part of WebCL – JavaScript bindings for OpenCL
 * http://webcl.nokiaresearch.com/
 *
 * Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
 *
 * Contact: Jari Nikara  ;jari.nikara@nokia.com;
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * version 2.1 as published by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 *
 *
 * The package is based on a published Khronos OpenCL 1.1 Specification,
 * see http://www.khronos.org/opencl/.
 *
 * OpenCL is a trademark of Apple Inc.
 */

/** \interface IWebCLContext
 * IWebCLContext interface abstracts a WebCL context.
 * \see cl_context
 */

#include "nsISupports.idl"
#include "nsISecurityCheckedComponent.idl"
#include "nsIVariant.idl"

#include "nsIDOMWebGLRenderingContext.idl"

#include "WebCL_types.idl"

interface IWebCLProgram;
interface IWebCLCommandQueue;
interface IWebCLDevice;
interface IWebCLMemoryObject;
interface IWebCLImageFormat;
interface IWebCLSampler;
interface IWebCLEvent;

[scriptable, uuid(0e5fba5c-091f-40db-a6a9-700ba50393d0)]
interface IWebCLContext : nsISecurityCheckedComponent
{
  /** Get context info.
   * \param aName Name of the info parameter.
   * \return The resulting value.
   * \see clGetContextInfo
   * \see WebCL_types
   */
  [implicit_jscontext]
  nsIVariant getContextInfo (in long aName);

  /** Creates a program object for a context, and loads the source code
   * specified by the text string aSource into the program object.
   * \param aSource The program source code.
   * \return A WebCLProgram instance.
   * \see clCreateProgramWithSource
   */
  [implicit_jscontext]
  IWebCLProgram createProgramWithSource (in string aSource);

  /** Create a command-queue on a specific device.
   * \param aDevice A WebCLDevice instance associated with the context.
   * \param aProperties Specifies a list of properties for the command queue.
   * \return A WebCLCommandQueue instance.
   * \see clCreateCommandQueue
   */
  [implicit_jscontext]
  IWebCLCommandQueue createCommandQueue (in nsISupports aDevice,
                                         in T_WebCLCommandQueueProperties aProperties);

  /** Creates a buffer object.
   * \param aFlags A bit-field that is used to specify allocation
   *  and usage information
   * \param aSize The size in bytes of the buffer memory object
   *  to be allocated.
   * \return A WebCLMemoryObject instance representing a buffer.
   * \see clCreateBuffer
   */
  [implicit_jscontext]
  IWebCLMemoryObject createBuffer (in T_WebCLMemFlags aFlags,
                                   in T_WebCLSize aSize);

  /** Creates a 2D image object.
   * \param aFlags A bit-field that is used to specify allocation
   * \param aImageFormat An object with "channelOrder" and "channelDataType"
   *                     properties of integer type. (Also "image_channel_order"
   *                     and "image_channel_data_type" are accepted but not
   *                     recommended for use.)
   * \param aWidth The width of the image in pixels.
   * \param aHeight The height of the image in pixels.
   * \param aRowPitch The scan-line pitch in bytes.
   * \return WebCLMemoryObject instance  representing a 2D image.
   * \see clCreateImage2D
   * \see getSupportedImageFormats
   */
  [implicit_jscontext]
  IWebCLMemoryObject createImage2D (in T_WebCLMemFlags aFlags,
                                    in nsIVariant aImageFormat,
                                    in T_WebCLSize aWidth,
                                    in T_WebCLSize aHeight,
                                    in T_WebCLSize aRowPitch);

  /** Creates a 3D image object.
   * \param aFlags A bit-field that is used to specify allocation
   * \param aImageFormat An object with "channelOrder" and "channelDataType"
   *                     properties of integer type. (Also "image_channel_order"
   *                     and "image_channel_data_type" are accepted but not
   *                     recommended for use.)
   * \param aWidth The width of the image in pixels.
   * \param aHeight The height of the image in pixels.
   * \param aDepth The depth of the image in pixels.
   * \param aRowPitch The scan-line pitch in bytes.
   * \param aSlicePitch The size in bytes of each 2D slice in the 3D image.
   * \return WebCLMemoryObject instance representing a 3D image.
   * \see clCreateImage3D
   * \see getSupportedImageFormats
   */
  [implicit_jscontext]
  IWebCLMemoryObject createImage3D (in T_WebCLMemFlags aFlags,
                                    in nsIVariant aImageFormat,
                                    in T_WebCLSize aWidth,
                                    in T_WebCLSize aHeight,
                                    in T_WebCLSize aDepth,
                                    in T_WebCLSize aRowPitch,
                                    in T_WebCLSize aSlicePitch);

  /** Creates a sampler object.
   * \param aNormalizedCoords Determines if the image coordinates specified
   * are normalized (true) or not (false).
   * \param aAddressingMode Specifies how out-of-range image coordinates are
   *  handled when reading from an image.
   * \param aFilterMode Specifies the type of filter that must be applied when
   *  reading an image.
   * \return WebCLMemoryObject instance representing a sampler.
   * \see clCreateSampler
   */
  [implicit_jscontext]
  IWebCLSampler createSampler (in boolean aNormalizedCoords,
                               in T_WebCLAddressingMode aAddressingMode,
                               in T_WebCLFilterMode aFilterMode);

  /** Get the list of image formats supported by an OpenCL implementation.
   * \param aFlags A bit-field that is used to specify allocation
   * \param aImageType Describes the image type and must be either
   *  CL_MEM_OBJECT_IMAGE2D or CL_MEM_OBJECT_IMAGE3D.
   * \return A JSArray of image formats wrapped in an nsIVariant. Each image
   *  format item is an object with properties channelOrder and
   *  channelDataType.
   * \see clGetSupportedImageFormats
   */
  [implicit_jscontext]
  nsIVariant getSupportedImageFormats (in T_WebCLMemFlags aFlags,
                                       in T_WebCLMemObjectType aImageType);

  /** Creates a user event object.
   * User events allow applications to enqueue commands that wait on
   * a user event to finish before the command is executed by the device.
   * \return A WebCLEvent instance.
   * \see clCreateUserEvent
   */
  [implicit_jscontext]
  IWebCLEvent createUserEvent ();

  /** Immediately releases all OpenCL-related resources if any are allocated
   * for this object. The object should not be used anymore after calling
   * this function.
   */
  void releaseCLResources ();
};
